RC Challan Detailed API

The following document highlights the details of the RC Challan Detailed API.

API Description

Objective

The RC Challan Detailed API takes the RC number and consent as input and returns the challan details for the given RC number. The response includes information related to the challan, vehicle, and owner details associated with the RC.

Input	Output
rcNumber, consent	Detailed challan data grouped under pending and disposed challans, including violation, vehicle, and owner-related details

API URL

https://ind-engine.thomas.hyperverge.co/v1/rcChallanDetailed

API Endpoint

rcChallanDetailed

Overview

The RC Challan Detailed API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should send a POST request with rcNumber and consent in the request body.

Method - POST

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload.	application/json
appId	Mandatory	The application identifier shared by HyperVerge.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey.	This should be both unique and easily associated with the user's journey in your application(s).

Inputs

The following table provides the details of the parameters required for the RC Challan Detailed API request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
rcNumber	Mandatory	string	The vehicle registration certificate number for which challan details are requested.	Should be a valid RC number string (for example: MH12AB1234).	Not Applicable
consent	Mandatory	string	The consent flag that authorizes retrieval of challan details.	yes or no.	Not Applicable

Sample Request

The following code shows the standard curl request for the RC Challan Detailed API:

curl --location 'https://ind-engine.thomas.hyperverge.co/v1/rcChallanDetailed' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
  "rcNumber": "<RC_Number>",
  "consent": "yes"
}'

Success Response

The following table outlines the details of the success response from the RC Challan Detailed API:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "message": "Challan Found",
    "data": {
      "pendingChallan": [
        {
          "challanNo": "<challan_no>",
          "challanDateTime": "<challan_date_time>",
          "challanPlace": "<challan_place>",
          "challanStatus": "<challan_status>",
          "sentToRegCourt": "<sent_to_reg_court>",
          "fineImposed": "<fine_imposed>",
          "dlNo": "<dl_no>",
          "driverName": "<driver_name>",
          "ownerName": "<owner_name>",
          "nameOfViolator": "<name_of_violator>",
          "department": "<department>",
          "stateCode": "<state_code>",
          "documentImpounded": "<document_impounded>",
          "offenceDetails": [
            {
              "act": "<act>",
              "reason": "<reason>"
            }
          ],
          "amountOfFineImposed": "<amount_of_fine_imposed>"
        }
      ],
      "disposedChallan": [
        {
          "challanNo": "<challan_no>",
          "challanDateTime": "<challan_date_time>",
          "challanPlace": "<challan_place>",
          "challanStatus": "<challan_status>",
          "sentToRegCourt": "<sent_to_reg_court>",
          "fineImposed": "<fine_imposed>",
          "dlNo": "<dl_no>",
          "driverName": "<driver_name>",
          "ownerName": "<owner_name>",
          "nameOfViolator": "<name_of_violator>",
          "department": "<department>",
          "stateCode": "<state_code>",
          "documentImpounded": "<document_impounded>",
          "offenceDetails": [
            {
              "act": "<act>",
              "reason": "<reason>"
            }
          ],
          "amountOfFineImposed": "<amount_of_fine_imposed>"
        }
      ]
    }
  },
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

The following table provides the details of the fields in a success response.

Parameter	Type	Description
status	string	The status of the API response.
statusCode	number	The HTTP status code returned by the API.
result	object	The object that contains the primary response information, including the message and challan data.
result.message	string	The response message that indicates whether challan records were found for the provided RC number.
result.data	object	The object that contains challan details grouped under pending and disposed challans.
result.data.pendingChallan	array	The list of challans that are still pending payment or resolution.
result.data.disposedChallan	array	The list of challans that have already been paid or resolved.
result.data.[pendingChallan/disposedChallan].challanNo	string	The unique challan number generated for the traffic violation.
result.data.[pendingChallan/disposedChallan].challanDateTime	string	The date and time when the challan was issued.
result.data.[pendingChallan/disposedChallan].challanPlace	string	The location where the traffic violation occurred.
result.data.[pendingChallan/disposedChallan].challanStatus	string	The current status of the challan.
result.data.[pendingChallan/disposedChallan].sentToRegCourt	string	The flag that indicates whether the challan has been forwarded to a regional court.
result.data.[pendingChallan/disposedChallan].fineImposed	string	The fine value associated with the violation.
result.data.[pendingChallan/disposedChallan].dlNo	string	The driving license number of the driver, if available.
result.data.[pendingChallan/disposedChallan].driverName	string	The name of the driver involved in the violation.
result.data.[pendingChallan/disposedChallan].ownerName	string	The name of the vehicle owner.
result.data.[pendingChallan/disposedChallan].nameOfViolator	string	The name of the person who committed the violation.
result.data.[pendingChallan/disposedChallan].department	string	The department responsible for issuing the challan.
result.data.[pendingChallan/disposedChallan].stateCode	string	The state code where the challan was issued.
result.data.[pendingChallan/disposedChallan].documentImpounded	string	The flag that indicates whether any document was impounded during the violation.
result.data.[pendingChallan/disposedChallan].offenceDetails	array	The list of offence entries associated with the challan.
result.data.[pendingChallan/disposedChallan].offenceDetails[].act	string	The law section under which the violation was recorded.
result.data.[pendingChallan/disposedChallan].offenceDetails[].reason	string	The description that explains the traffic violation.
result.data.[pendingChallan/disposedChallan].amountOfFineImposed	string	The final amount of fine imposed for the challan entry.
metadata	object	The object that contains request tracing details.
metadata.requestId	string	The unique request identifier generated for the API call.
metadata.transactionId	string	The unique transaction identifier passed in the API request.

Error Responses

The following are some error responses from the RC Challan Detailed API:

RC Number is invalid

{
  "status": "failure",
  "statusCode": 400,
  "message": "RC Number is invalid",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

RC Number is required

{
  "status": "failure",
  "statusCode": 400,
  "message": "RC Number is required",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Consent is required

{
  "status": "failure",
  "statusCode": 400,
  "message": "Consent is required",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid consent enum

{
  "status": "failure",
  "statusCode": 400,
  "message": "Input Validation Error: consent is not one of enum values: yes,no"
}

Missing consent property

{
  "status": "failure",
  "statusCode": 400,
  "message": "Input Validation Error: requires property \"consent\""
}

Missing rcNumber property

{
  "status": "failure",
  "statusCode": 400,
  "message": "Input Validation Error: requires property \"rcNumber\""
}

Challan not found

{
  "status": "failure",
  "statusCode": 404,
  "message": "Challan not found",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Maximum retry limit exceeded

{
  "status": "failure",
  "statusCode": 429,
  "message": "Maximum retry limit exceeded",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Internal Server Error

{
  "status": "failure",
  "statusCode": 500,
  "message": "Internal Server Error",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

External source downtime

{
  "status": "failure",
  "statusCode": 503,
  "message": "External source downtime",
  "error": "EXTERNAL_DOWNTIME",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Response Details

A failure response contains a failure status with the relevant status code and error message. The following table lists the error responses for the RC Challan Detailed API:

Status Code	Error Message	Error Description	Error Resolution
400	RC Number is invalid	The provided RC number format is incorrect.	The client should validate and send a correctly formatted RC number.
400	RC Number is required	The RC number field is empty in the request body.	The client should pass a non-empty value for rcNumber.
400	Consent is required	The consent value required for processing is not provided.	The client should pass consent with a valid value.
400	Input Validation Error: consent is not one of enum values: yes,no	The consent value is outside the supported enum values.	The client should pass consent only as yes or no.
400	Input Validation Error: requires property "consent"	The consent field is missing from the request body.	The client should include the consent field in the request payload.
400	Input Validation Error: requires property "rcNumber"	The rcNumber field is missing from the request body.	The client should include the rcNumber field in the request payload.
404	Challan not found	The challan details are not available for the provided RC number.	The client should verify the RC number and retry with valid details.
429	Maximum retry limit exceeded	The request rate has exceeded the permitted threshold.	The client should retry after applying backoff and request throttling.
500	Internal Server Error	The server encountered an unexpected condition while processing the request.	The client should retry after some time and contact support if the issue persists.
503	External source downtime	The upstream source required for challan retrieval is temporarily unavailable.	The client should retry after some time when the source service is restored.